NeXTSTEP 3.2 for Intel/NeXTSTEP 3.2 for Intel.iso/NextLibrary/Documentation/Sybase/DBLIB/Intro.nr

Text File | 1993-04-22 | 52.5 KB | 1,422 lines

.Ds U
.Pt Section
.Ff 1 "Introduction" "\*L Reference Manual"
.H1 "Overview of \*L"
.Ih "\*L, overview of"
.Ih "\*L, contents of"
.Ss \*L TM
is a set of C routines and macros that allow your
application to interact with the
.Ss \*S TM .
It includes routines that send
.Ss \*N TM
commands
to the \*S and others that process the results of those commands.
Other routines handle error conditions, perform data
conversion, and provide a variety of information about
the interaction with the \*S.
\*L also contains several header files
that define structures and values used by the routines.
Versions of \*L have been developed for a number
of languages besides C, including COBOL, FORTRAN, Ada, and
Pascal.
.H2 "\*N"
.Ih "\*N"
.Ih "SQL database language"
\*N is the enhanced SYBASE\(rg version of the SQL
database language.
The application uses it to communicate with the \*S.
\*N provides commands for creating and
manipulating database objects, as well as for
inserting, updating, and selecting data.
The SYBASE enhancements include data integrity features and
stored procedures.
.Ih "stored procedures, \*N"
.Ih "procedures, stored, \*N"
Stored procedures allow much of an application's
processing logic to be shifted from the application
proper to the \*S.
They can contain most \*N
statements, including \*N
control-of-flow statements.
Furthermore, stored procedures are pre-compiled, so
the statements don't have to be parsed each time the
procedure is executed.
.H2 "Applications for \*L"
.Ih "applications, \*L"
.Ih "\*L applications"
\*L enables the database to become an integral
part of an application.
\*N statements can be incorporated into the
application, allowing the application to retrieve and
update values from a database.
Through \*L, values from the database can
be placed in program variables for manipulation by the
application.
Conversely, values in program variables can be inserted
into the database.
.LP
Although \*L contains a large number of routines,
giving the application a great deal of control over its
interaction with the \*S, most applications require only
a few of the routines.
The actual process of connecting with the \*S, sending
\*N commands to the \*S, and processing the resulting data
is simple and straightforward.
.H2 "Comparing the Library Approach to Embedded SQL"
The \*L approach is distinctly different from the ``embedded SQL''
type of host language interface that some database management systems
provide.
In contrast to an embedded SQL interface, the
\*L interface does not require a host language pre-compiler.
Avoiding preprocessing in this way makes applications
involving a database more straightforward to write and to debug.
The \*L routines are ordinary C routines and are not
preprocessed into some intermediate form.
.H2 "Other SYBASE Development Tools"
.Ih "SYBASE development tools"
.Ih "tools, development"
.Ih "development tools, SYBASE"
SYBASE provides a complete development environment.
In addition to control over database access through
\*L, SYBASE offers optional tools for creating forms-based,
event-driven applications.
These tools are
.Ss \*A TM
and the
.Ss \*F TM
set of routines.
.Ih "\*F"
\*A is an editor for creating forms and specifying event-driven
processing.
.Ih "\*A editor"
.Ih "editor, \*A"
\*F is a set of C routines that support forms-based, event-driven
processing.
Just as \*L routines provide an application with access to the \*S and database objects,
\*F routines provide access to the form and its objects.
A forms-based application typically contains both
\*F and \*L routines.
For more information, see the \f2\*A User's Guide\f1 and the \f2\*F Reference Manual\f1.
.H1 "Communicating with the \*S"
\*L routines communicate with the \*S through the
DBPROCESS structure.
Through the DBPROCESS, commands are sent to the \*S and query results are returned to the application.
.Ih "DBPROCESS structure"
.Ih "\*S, communicating with"
One of the first routines an application typically calls is \f2dbopen()\f1,
which logs the application into a \*S and allocates and initializes a DBPROCESS.
.Ih "dbopen"
This DBPROCESS then serves as the connection between the application and the \*S.
Most \*L routines require a DBPROCESS as the first parameter.
.LP
An application can have multiple open DBPROCESSes, connected to one or more \*Ss.
.Ih "DBPROCESSes, multiple"
.Ih "\*Ss, multiple"
.Ih "multiple \*Ss"
For instance, an application that has to
perform database updates in the midst of processing
the results of a query needs a separate DBPROCESS for each task.
As another example,
to select data from one \*S and update a database on another \*S,
an application needs two DBPROCESSes\(emone for each \*S.
Each DBPROCESS in an application functions independently of any other DBPROCESS.
.Ih "DBPROCESSes, multiple"
.LP
The DBPROCESS structure points to a command buffer that contains \*N
commands for transmission to the \*S.
.Ih "command buffer"
.Ih "buffer, command"
It also points to result rows returned from the \*S\(emeither single rows or buffers
of rows if buffering has been specified.
.Ih "result rows"
.Ih "rows, result"
In addition, it points to a message buffer that contains error and informational
messages returned from the \*S.
.Ih "message buffer"
.Ih "buffer, message"
.LP
The DBPROCESS also contains a wealth of information on various aspects of \*S interaction.
Many of the \*L routines deal with extracting information from
the DBPROCESS.
Applications should access and manipulate components of the DBPROCESS structure only
through \*L routines, and not directly.
.LP
One other important structure is the LOGINREC.
.Ih "LOGINREC structure"
.Ih "login record"
.Ih "record, login"
It contains typical login information, such as the username and password,
which the \f2dbopen()\f1 routine uses when logging into a \*S.
\*L routines can specify the information in the LOGINREC.
.H1 "\*L Programming"
.Ih "programming with \*L"
.Ih "\*L programming, steps involved"
Programming with \*L typically involves a few basic steps:
.Bl "1."
Logging into a \*S.
.Bl "2."
Placing \*N commands into a buffer and sending them to the \*S.
.Bl "3."
Processing the results, if any, returned from the \*S, one command
at a time and one result row at a time.
The results can be placed in program variables, where
they can be manipulated by the application.
.Bl "4."
Handling \*L errors and \*S messages.
.Bl "5."
Closing the connection with the \*S.
.Bz
The example below shows the basic framework of many
\*L applications.
.Ih "\*L program, framework of"
.Ih "program, \*L"
The program opens a connection to a \*S, sends a \*N SELECT
command to the \*S, and processes the set of rows
resulting from the SELECT.
For brevity's sake, this program does not include the
error or message handling routines;
those routines are illustrated in the example programs in
the \f2\*L Reference Supplement\f1.
.SD
.ps -2
.vs -2
.in +3n
.ta +4n +4n +4n +4n +4n +4n +4n
.ne 5
#include <sybfront.h>
#include <sybdb.h>
#include <syberror.h>

/* Forward declarations of the error handler and message handler. */
int             err_handler();
int             msg_handler();

main()
{
    DBPROCESS     *dbproc;       /* The connection with the \*S. */
    LOGINREC      *login;        /* The login information. */
    DBCHAR         name[40];
    DBCHAR         city[20];

    /* Initialize DB-Library. */
.mc |
    if (dbinit() == FAIL)
        exit(ERREXIT);

.mc
    /*
    ** Install user-supplied error-handling and message-handling routines.
    ** The code for these is omitted from this example for conciseness.
     */
    dberrhandle(err_handler);
    dbmsghandle(msg_handler);

    /* Get a LOGINREC.  */
    login = dblogin();
    DBSETLPWD(login, "server_password");
    DBSETLAPP(login, "example");

    /* Get a DBPROCESS structure for communication with the \*S. */
    dbproc = dbopen(login, NULL);

    /*
    ** Retrieve some columns from the "authors" table in the
    ** "pubs" database.
    */

    /* First, put the command into the command buffer. */
    dbcmd(dbproc, "select au_lname, city from pubs..authors");
    dbcmd(dbproc, " where state = 'CA' ");

    /* Send the command to the \*S and start execution. */
    dbsqlexec(dbproc);

    /* Process the command. */
    if (dbresults(dbproc) == SUCCEED)
    {
        /* Bind results to program variables. */
        dbbind(dbproc, 1, STRINGBIND, (DBINT)0, name);
        dbbind(dbproc, 2, STRINGBIND, (DBINT)0, city);

        /* Retrieve and print the result rows. */
        while (dbnextrow(dbproc) != NO_MORE_ROWS)
        {
            printf ("%s: %s\en", name, city);
        }
    }

    /* Close the connection to the \*S. */
    dbexit();
}
.in -3n
.ED
.ps +2
.vs +2
.LP
The example illustrates features common to most \*L
applications:
.Bl
\f3Header files\f1.
.Ih "header files"
.Ih "include files"
.Ih "files, header"
.Ih "files, include"
Two header files, \f2sybfront.h\f1 and \f2sybdb.h\f1,
.Ih "sybfront.h"
.Ih "sybdb.h"
are required in all source files that contain calls to
\*L routines.
\f2sybfront.h\f1 must appear first in the file.
It defines symbolic constants such as function return values,
described in the Section 2 manual pages, and the
exit values STDEXIT and ERREXIT.
.Ih "symbolic constants"
.Ih "constants, symbolic"
.Ih "STDEXIT"
.Ih "ERREXIT"
These exit values can be used as the argument for
the C standard library function \f2exit()\f1.
Since they are defined appropriately for the operating
system running the program,
their use provides a system-independent approach to exiting
the program.
\f2sybfront.h\f1 also includes typedefs for datatypes that can be used in
program variable declarations.
These datatypes are described a little later.
.sp 0.5v
\f2sybdb.h\f1 contains additional definitions and typedefs, most of which are meant
to be used only by the \*L routines and should not be directly accessed
by the program.
Of chief importance in \f2sybdb.h\f1 is the typedef for the DBPROCESS structure.
As discussed earlier, the DBPROCESS structure should be manipulated
only through \*L routines; you should not access its components directly.
To ensure compatibility with future releases of \*L,
use the contents of \f2sybdb.h\f1 only as documented in the \*L manual pages.
.sp 0.5v
The third header file in the example, \f2syberror.h\f1, contains error severity
values and should be included if the program refers
to those values.
.Ih "syberror.h"
.mc |
.Bl
\f3dbinit()\f1.
.Ih "dbinit"
This routine initializes \*L.
It must be the first \*L routine in the program.
Not all \*L environments currently require the \f2dbinit()\f1 call.
However, to ensure future compatibility and portability, you should
include this call at the start of all \*L programs.
.mc
.Bl
\f3dberrhandle() and dbmsghandle()\f1.
.Ih "dberrhandle"
.Ih "dbmsghandle"
.Ih "error handling"
.Ih "message handling"
.Ih "errors, \*L"
.Ih "errors, \*S"
.Ih "\*L errors"
.Ih "\*S errors"
\f2dberrhandle()\f1 installs a user-supplied error-handling routine, which
gets called automatically whenever the application encounters
a \*L error.
Similarly, \f2dbmsghandle()\f1 installs a message-handling routine, which
gets called in response to informational or error messages returned from the \*S.
The error and message handling routines are user-supplied.
Sample handlers have not been supplied with this example, but are included at the end
of each example program in
the \f2\*L Reference Supplement\f1.
.Bl
\f3dblogin()\f1.
.Ih dblogin
.Ih LOGINREC
This routine supplies a LOGINREC structure, which \*L will use to log into a \*S.
The two macros that follow set certain components of the LOGINREC.
\f2DBSETLPWD()\f1 sets the password that \*L will use when logging in.
.Ih DBSETLPWD
\f2DBSETLAPP()\f1 sets the name of the application, which will appear in the \*S's \f2sysprocess\f1 table.
.Ih DBSETLAPP
Routines are available for setting other aspects of the LOGINREC.
However, in most environments these routines are optional; the LOGINREC contains default values
for each of the values they set.
.Bl
\f3dbopen()\f1.
The \f2dbopen()\f1 routine opens a connection between the application and a \*S.
.Ih dbopen
It uses the LOGINREC supplied by \f2dblogin()\f1 to log into the server.
It returns a DBPROCESS structure, which serves as the conduit for information
between the application and the server.
After this routine has been called, the application is connected with the \*S
and can now send \*N commands to the \*S and process any results.
.Bl
\f3dbcmd()\f1.
.Ih dbcmd
.Ih "command buffer"
.Ih "buffer, command"
.Ih \*N commands, processing"
This routine fills the command buffer with \*N commands, which
can then be sent to the \*S.
Each succeeding call to \f2dbcmd()\f1 simply adds the supplied text
to the end of any text already in the buffer.
It is the programmer's responsibility to supply necessary blanks
between words, such as the blank at the beginning of the text
in the second \f2dbcmd()\f1 call in the example.
Multiple commands can be included in the buffer.
This example only shows how to send and process a single command, but
\*L is designed to allow an application to send multiple commands to a \*S and process
each command's set of results separately.
.Bl
\f3dbsqlexec()\f1.
.Ih dbsqlexec
This routine executes the command buffer; that is, it sends the contents of the buffer
to the \*S, which parses and executes them.
.Bl
\f3dbresults()\f1.
.Ih dbresults
This routine gets the results of the current \*N command ready for processing.
In this example, the buffer contains only a single command, so \f2dbresults()\f1 is
called just once.
If the buffer contained multiple commands,
the program would need to call \f2dbresults()\f1 once for each command in the buffer.
.Bl
\f3dbbind()\f1.
.Ih dbbind
\f2dbbind()\f1 binds result columns to program variables.
In the example, the first call to \f2dbbind()\f1 binds the first result
column to the variable ``name''.
In other words, when the program reads a result
row by calling \f2dbnextrow()\f1,
the contents of the first result column (``au_lname'') will get placed
in the ``name'' variable.
The second \f2dbbind()\f1 call
binds the second result column to the variable ``city''.
.sp 0.5v
The datatype of both bindings is ``STRINGBIND,'' one of several binding types
available for character data.
The binding type must correspond to the datatype of the specified program variable.
In this example the ``name'' variable has a DBCHAR datatype, a
\*L-defined datatype that accepts a STRINGBIND result.
By means of the binding type parameter,
\f2dbbind()\f1 supports a wide variety of type conversions, allowing
the datatype of the receiving variable to differ from
the datatype of the result column.
.Bl
\f3dbnextrow()\f1.
.Ih dbnextrow
This routine reads a row and places the results in the program variables
specified by the earlier \f2dbbind()\f1 calls.
Each successive call to \f2dbnextrow()\f1 reads another result row, until the last row
has been read and NO_MORE_ROWS is returned.
Processing of the results must take place inside the \f2dbnextrow()\f1 loop, because
each call to \f2dbnextrow()\f1 overwrites the previous values in the program variables.
This example program merely prints each row's contents.
.Bl
\f3dbexit()\f1.
.Ih dbexit
This routine closes the \*S connection and de-allocates the DBPROCESS.
.mc |
It also cleans up any structures initialized by \f2dbinit()\f1.
It must be the last \*L routine in the program.
.Bz
.mc
Although \*L contains a great number of routines, much can be accomplished
with just the few routines shown in this example.
.H2 "\*L Datatypes"
.Ih "datatypes, \*L"
.Ih "\*L datatypes"
\*L defines datatypes for \*S data.
These datatypes begin with ``SYB'' (\f2e.g.,\f1 SYBINT4, SYBCHAR, SYBMONEY).
Various routines require these \*S datatypes as parameters.
\*L also provides typedefs for use in program variable declarations.
These typedefs begin with the prefix ``DB'' (\f2e.g.,\f1 DBINT, DBCHAR, DBMONEY, etc.).
By using them, you ensure that your program variables will be compatible with the
\*S datatypes.
Section 2 includes a manual page, \f2types\f1, that lists the \*S datatypes and
the \*L program variable types.
.LP
The \f2dbconvert()\f1 routine provides a way to convert data from one \*S datatype
to another.
.Ih dbconvert
It supports conversion between most datatypes.
Since the \*S datatypes correspond directly to the \*L datatypes,
you can use \f2dbconvert()\f1 widely within your application.
The routines that bind \*S result columns to program variables\(em\f2dbbind()\f1 and
\f2dbaltbind()\f1\(emalso provide type conversion.
.Ih dbbind
.Ih dbaltbind
.H1 "\*L Routines"
.Ih "\*L routines, categories of"
.Ih "Routines, categories of"
The \*L routines and macros handle a large variety of tasks, which are divided
in this section into a number of categories:
.Bl
Initialization
.Bl
Command Processing
.Bl
Results Processing
.Bl
Error and Message Handling
.Bl
Information Retrieval
.Bl
Browse Mode
.Bl
Text and Image Handling
.Bl
Datatype Conversion
.Bl
Process Control Flow
.Bl
Remote Procedure Call Processing
.Bl
Cleanup
.Bl
Miscellaneous
.Bz
The routines and macros are described in individual manual pages
in Section 2.
They all begin with the prefix ``db''.
The routines are named with lowercase letters; the macros are capitalized.
.LP
In addition, \*L includes two special libraries:
.Bl
Bulk Copy
.Bl
Two-Phase Commit Service
.Bz
The routines in these libraries are described in manual pages in Section 3.
The bulk copy routines begin with the prefix ``bcp''.
The two-phase commit routines have no standard prefix.
.H2 "Initialization"
.Ih "initialization routines"
.Ih "routines, initialization"
These routines set up and define the connection between
the application program and a \*S.
They handle such tasks as allocating and defining
a LOGINREC structure, opening a connection to a \*S, and allocating
a DBPROCESS structure.
Only a few of the routines are absolutely necessary in every
\*L program; in particular, an application requires
\f2dbinit()\f1, \f2dblogin()\f1 and \f2dbopen()\f1.
The lists below specify the initialization routines in the approximate order
in which a program is likely to call them.
.mc |
.H3 "Initializing \*L"
.Ih "\*L, initializing"
.Ih "initializing \*L"
.LP
.IP \f6dbinit\f1 18
.Ih dbinit
Initializes underlying structures used by \*L.
.mc
.H3 "Setting Up the LOGINREC"
.Ih "LOGINREC, setting up"
.LP
.IP \f6dblogin\f1 18
.Ih dblogin
Allocates a LOGINREC structure for subsequent use by \f2dbopen()\f1.
.IP \f6DBSETLUSER\f1
Sets the \*S username in the LOGINREC.
.IP \f6DBSETLPWD\f1
Sets the \*S password in the LOGINREC.
.IP \f6DBSETLAPP\f1
Sets the application name in the LOGINREC.
.IP \f6DBSETLHOST\f1
Sets the host name in the LOGINREC.
.mc |
.IP \f6dbloginfree\f1
.Ih dbloginfree
Frees a LOGINREC structure.
.mc
.H3 "Establishing a \*S Connection"
.Ih "\*S connection, establishing"
.LP
.IP \f6dbsetifile\f1 18
Specifies the \f2interfaces\f1 file that \f2dbopen()\f1
will use to connect to a \*S.
.mc |
.IP \f6dbsetconnect\f1
\f2OS/2, MS-DOS\(rg and Macintosh\(rg only\f1.
Allocates and initializes a network connection structure
that \f2dbopen()\f1 will use when opening a connection
to a \*S.
This routine can be used in place of the \f2interfaces\f1 file,
which ordinarily determines which \*S
a new DBPROCESS will connect to.
.mc
.IP \f6dbsetlogintime\f1
Sets the number of seconds \*L will wait for a \*S
to respond to a request by \f2dbopen()\f1 for a DBPROCESS
connection.
.IP \f6dbopen\f1
.Ih dbopen
Sets up communication with the network,
logs into a \*S using the LOGINREC, initializes any
options specified in the LOGINREC, and allocates a DBPROCESS.
An application can open multiple connections to a \*S, each
connection having its own DBPROCESS.
An application can also open multiple connections to multiple \*Ss.
.H3 "Setting the Database"
.Ih "database, setting"
.LP
.IP \f6dbuse\f1 18
Sets the current database.
This routine is equivalent to the \*N USE command and
can be called repeatedly in an application.
.H2 "Command Processing"
.Ih "command processing routines"
.Ih "routines, command processing"
The application communicates with a \*S through \*N commands.
It enters the commands into a command buffer, which the DBPROCESS points to.
.Ih "command buffer"
.Ih "buffer, command"
The application can place multiple commands in the command buffer, and the
set of commands in the buffer is known as the command batch.
.Ih "command batch"
.Ih "batch, command"
The application then sends the command batch to a \*S, which executes the commands
in the order entered in the buffer.
.H3 "Building the Command Batch"
.Ih "command batch, building"
.LP
These routines add commands to the buffer or clear the buffer.
.IP \f6dbcmd\f1 18
.Ih dbcmd
Adds text to the command buffer.
It may be called repeatedly to add multiple commands, or parts of commands.
The text added with each successive call is concatenated to the previous
text.
.IP \f6dbfcmd\f1
Adds text to the command buffer using \f2sprintf()\f1-type formatting.
This routine is the same as \f2dbcmd()\f1, except that it allows arguments
to be substituted into the text.
.IP \f6dbfreebuf\f1
Clears the command buffer.
The command buffer is automatically cleared
before a batch of commands is entered.
To clear it at other times or when the DBNOAUTOFREE option has been set,
use \f2dbfreebuf()\f1.
.H3 "Accessing the Command Batch"
.Ih "command batch, accessing"
.LP
These routines may be used to examine and copy parts of the command buffer.
.IP \f6dbgetchar\f1 18
Returns a pointer to a particular character in the command buffer.
.IP \f6dbstrlen\f1
Returns the length of the command buffer.
.IP \f6dbstrcpy\f1
Copies a portion of the command buffer to a program variable.
This routine is particularly valuable for debugging, because
it can tell you exactly what was sent to the \*S.
.Ih "debugging"
.H3 "Executing the Command Batch"
.Ih "command batch, executing"
.LP
Once \*N commands have been entered in the
buffer, they can be sent to a \*S for execution.
.IP \f6dbsqlexec\f1 18
.Ih dbsqlexec
Sends the contents of the command buffer to a \*S for execution.
Once \f2dbsqlexec()\f1 has returned SUCCEED, \f2dbresults()\f1 must
be called to process the results.
Calling \f2dbsqlexec()\f1 is equivalent to calling \f2dbsqlsend()\f1
followed by \f2dbsqlok()\f1.
.IP \f6dbsqlsend\f1
Sends the contents of the command buffer to a \*S for execution.
Unlike \f2dbsqlexec()\f1, this routine does not wait for a response
from the \*S.
When \f2dbsqlsend()\f1 has returned SUCCEED, \f2dbsqlok()\f1 must
be called to verify the correctness of the command batch.
.IP \f6dbsqlok\f1
Waits for results from the \*S and verifies the
correctness of the instructions the server is responding to.
This routine is used in conjunction with \f2dbsqlsend()\f1, \f2dbrpcsend()\f1,
and \f2dbmoretext()\f1.
After a successful \f2dbsqlok()\f1 call, the application must call \f2dbresults()\f1
to process the results.
.H3 "Setting and Clearing Command Options"
.Ih "command options"
.Ih "options, command"
.LP
The application can set a
number of \*S and \*L command options.
Among them are DBPARSEONLY, which causes the \*S to parse but not
execute the command batch,
and DBBUFFER, which provides buffering of result rows.
For a list of all available options and their significance, see
the \f2options\f1 manual page at the end of Section 2.
.IP \f6dbsetopt\f1 18
Sets an option.
.IP \f6dbclropt\f1
Clears an option.
.IP \f6dbisopt\f1
Determines whether a particular option is set.
.H2 "Results Processing"
.Ih "results processing routines"
.Ih "routines, results processing"
Once a command batch has been executed in the \*S,
indicated by \f2dbsqlexec()\f1 or \f2dbsqlok()\f1
returning SUCCEED, the application must process any results.
Result rows are returned by
SELECT commands and EXECUTEs on stored procedures
that contain SELECT commands.
.LP
There are two types of result rows:
regular rows and compute rows.
.Ih "rows, types of"
.Ih "result rows, types of"
.Ih "regular rows"
.Ih "rows, regular"
.Ih "compute rows"
.Ih "rows, compute"
Regular rows are generated from columns in a
SELECT command's \f2select-list\f1; compute
rows are generated from columns in a SELECT
command's COMPUTE clause.
Since these two types of rows contain very different data,
the application must process them separately.
.LP
The results for each command in a batch
are returned to the application separately.
Within each command's set of results,
the result rows are processed one at a time.
.H3 "Setting Up the Results"
.Ih "results, setting up"
.LP
.IP \f6dbresults\f1 18
Sets up the results of the next command in the batch.
This routine must be called once for each command in the
batch, whether or not the command returns rows.
.Ih dbresults
.sp 0.5v
\f2dbresults()\f1 must be called after \f2dbsqlexec()\f1
or \f2dbsqlok()\f1 has returned SUCCEED, but before
calls to \f2dbbind()\f1 or \f2dbnextrow()\f1.
.H3 "Getting Result Data"
.Ih "result data, getting"
.LP
The simplest way to get result data is to bind result
columns to program variables, using \f2dbbind()\f1 and
\f2dbaltbind()\f1.
.Ih dbbind
.Ih dbaltbind
.Ih "result data, binding to variables"
Then, when the application calls \f2dbnextrow()\f1 to read a result row
(see the next section),
\*L will automatically place copies of the columns' data
into the program variables to which they are bound.
The application must call \f2dbbind()\f1 and \f2dbaltbind()\f1 after
a \f2dbresults()\f1 call but before the first call to \f2dbnextrow()\f1.
.LP
You can also access a result column's data directly with \f2dbdata()\f1
and \f2dbadata()\f1, which return pointers to the data.
\f2dbdata()\f1 and \f2dbadata()\f1 have the advantage of providing
access to the actual data, not a copy of the data.
.Ih dbdata
.Ih dbadata
.Ih "result data, accessing directly"
These routines are frequently used in conjunction with
\f2dbdatlen()\f1 and \f2dbadlen()\f1, which return the length
of the data and are described later, in the section ``Information Retrieval.''
When you are accessing data directly with these routines, you do not
perform any preliminary binding of result columns to program variables.
Simply call \f2dbdata()\f1 or \f2dbadata()\f1 after a \f2dbnextrow()\f1 call.
.IP \f6dbbind\f1 18
Binds a regular row result column to a program variable.
.IP \f6dbaltbind\f1
Binds a compute row result column to a program variable.
.IP \f6dbdata\f1
Returns a pointer to the data for a regular row result column.
.IP \f6dbadata\f1
Returns a pointer to the data for a compute row result column.
.H3 "Reading Result Rows"
.Ih "result rows, reading"
.Ih "row data, reading"
.LP
Once \f2dbresults()\f1 has returned SUCCEED and any binding
of columns to variables has been specified, the application is ready
to process the results.
The first step is to make the result rows available to the application.
The \f2dbnextrow()\f1 routine accomplishes this.
.Ih dbnextrow
Each call to \f2dbnextrow()\f1 reads the next row returned from the \*S.
The row is read directly from the network.
.LP
Once a row has been read in by \f2dbnextrow()\f1, the application can
perform any processing desired on the data in the row.
If the result columns have been bound to program variables,
the data in the row will have been automatically copied into the variables.
Alternatively, the data is accessible through \f2dbdata()\f1 or \f2dbadata()\f1.
.LP
Rows read in by \f2dbnextrow()\f1 may be automatically saved in a row buffer, if desired.
The application accomplishes this
by setting the DBBUFFER option with the \f2dbsetopt()\f1 routine.
Row buffering is useful for applications that need to process result rows
in a non-sequential manner.
.Ih "buffer, row"
.Ih "row buffer"
.Ih "DBBUFFER option"
Without row buffering, the application must process each row as it is read in
by \f2dbnextrow()\f1, because the next call to \f2dbnextrow()\f1 will
overwrite the row.
If the application has enabled row buffering,
the rows are added to a row buffer as they are read in by \f2dbnextrow()\f1.
The application can then use the \f2dbgetrow()\f1 routine
to skip around in the buffer and return to previously read rows.
Since row buffering carries a memory and performance penalty, use it
with discretion.
Note that row buffering has nothing to do with network buffering
and is a completely independent issue.
.LP
Routines are also available to print result rows in a default format.
Because the format is predetermined, these routines are of limited usefulness
and are appropriate primarily for debugging.
.Ih debugging
.LP
Note that \*L processes results one command at a time.
When the application has read all the results for one command,
it must call \f2dbresults()\f1 again to set up the results for the next
command in the command buffer.
.IP \f6dbnextrow\f1 18
Reads in the next row.
The return value from \f2dbnextrow()\f1 tells the application whether the
row is a regular row or a compute row, whether the row buffer is full, and
whether the last result row has been read.
.IP \f6dbgetrow\f1
Reads the specified row in the row buffer.
This routine provides the application with access to buffered rows that have
been previously read by \f2dbnextrow()\f1.
.IP \f6dbclrbuf\f1
Drops rows from the row buffer.
.IP \f6dbprrow\f1
Prints all the result rows in a default format.
When this routine is used, the program does not need to bind results or
call \f2dbnextrow()\f1.
.IP \f6dbprhead\f1
Prints default column headings for result rows.
This routine is used in conjunction with \f2dbprrow()\f1.
.H3 "Canceling Results"
.Ih "results, canceling"
.LP
.IP \f6dbcancel\f1 18
Cancels results from the current command batch.
This routine cancels \f2all\f1 the commands in the current batch.
.IP \f6dbcanquery\f1
Cancels any rows pending from the most recently executed query.
.mc |
.H3 "Handling Stored Procedure Results"
.Ih "stored procedure results, handling"
.Ih "procedure, stored"
.LP
A call to a stored procedure is made through either
a remote procedure call, discussed in a later section, or
a \*N EXECUTE command.
The call can generate several types of results.
First of all, a stored procedure that contains SELECT statements
will return result rows in the usual fashion.
Each successive call
to \f2dbresults()\f1 will access the set of rows from the next
SELECT statement in the stored procedure.
These rows can be processed, as usual, with \f2dbnextrow()\f1.
.LP
Second, stored procedures can contain ``return parameters.''
.Ih "stored procedure, return parameters"
.Ih "return parameters from stored procedures"
Return parameters provide stored procedures with a ``call-by-reference'' capability.
Any change that a stored procedure makes internally
to the value of a return parameter is available
to the calling program once it has processed
all of the stored procedure's result rows, if any, by calling
\f2dbresults()\f1 and \f2dbnextrow()\f1.
A number of routines, described below, process return parameter values.
.LP
Third, stored procedures can return a status number, which the program can access through
routines described below.
.Ih "stored procedure, status number returned by"
.Ih "return status, stored procedure"
.Ih "status value, stored procedure"
.LP
.IP \f6dbretdata\f1 18
Returns a pointer to a return parameter value.
.IP \f6dbretlen\f1
Returns the length of a return parameter value.
.IP \f6dbrettype\f1
Returns the datatype of a return parameter value.
.IP \f6dbretname\f1
Returns the name of the return parameter associated with a particular value.
.IP \f6dbnumrets\f1
Returns the number of return parameter values generated by a stored procedure.
.IP \f6dbretstatus\f1
Returns the stored procedure's status number.
.IP \f6dbhasretstat\f1
Indicates whether the current command or remote procedure call
generated a stored procedure status number.
.mc
.H3 "Miscellaneous Results Processing"
.LP
.IP \f6dbsettime\f1 18
Sets the number of seconds that \*L will wait for a \*S response.
.IP \f6DBGETTIME\f1
Gets the number of seconds that \*L will wait for a \*S response.
.H2 "Error and Message Handling"
.Ih "error handling routines"
.Ih "routines, error handling"
.Ih "message handling routines"
.Ih "routines, message handling"
.Ih "errors, \*L"
.Ih "errors, \*S"
.Ih "messages, \*S"
.Ih "\*L errors"
.Ih "\*S errors"
.Ih "\*S messages"
\*L applications must deal with two types of errors and messages:
those from the \*S (known as ``messages'') and those generated
by \*L routines (known as ``errors'').
The \*S can return both informational and error messages to the application.
In addition, \*L has its own set of possible warnings and errors.
.LP
See the \f2\*S Reference Supplement\f1 for a list of \*S messages.
For a list of \*L errors, see the \f2errors\f1 manual page at the end of Section 2.
.LP
\*L provides an easy way to centralize error and message
handling.
Using \f2dbmsghandle()\f1 and \f2dberrhandle()\f1, you can
install your own message and error handling routines.
.Ih dbmsghandle
.Ih dberrhandle
When a message or error then occurs, \*L will automatically call the
appropriate user-supplied function, providing information to that
function on the nature of the message or error.
The error and message handling logic can thus be relegated to two
functions in your application.
.IP \f6dbmsghandle\f1 18
Installs a user function to handle \*S informational and error messages.
.IP \f6dberrhandle\f1 18
Installs a user function to handle \*L error messages.
.IP \f6DBDEAD\f1
.Ih "DBPROCESS, dead"
.Ih "DBDEAD"
Determines whether a particular DBPROCESS is dead.
When a DBPROCESS is dead, the current \*L routine
fails, causing the error handler to be called.
.H2 "Information Retrieval"
.Ih "information retrieval routines"
.Ih "routines, information retrieval"
Information covering several areas,
including regular result columns,
compute result columns, row buffers, and the command state,
can be retrieved from the DBPROCESS structure.
As mentioned earlier, regular result columns correspond to
columns in the SELECT command's \f2select-list\f1 and
compute result columns correspond to columns in the
SELECT command's optional COMPUTE clause.
.H3 "Regular Result Column Information"
.LP
These routines can be called after \f2dbsqlexec()\f1 returns
SUCCEED.
.IP \f6dbnumcols\f1 18
Determines the number of columns in the current set of results.
.IP \f6dbcolname\f1
Returns the name of a regular result column.
.IP \f6dbcollen\f1
Returns the maximum length for a regular column's data.
.IP \f6dbcoltype\f1
Returns the \*S datatype for a regular result column.
.IP \f6dbdatlen\f1
Returns the actual length of a regular column's data.
This routine is often used in conjunction with \f2dbdata()\f1.
The value returned by \f2dbdatlen()\f1 is different for each regular row read by
\f2dbnextrow()\f1.
.mc |
.IP \f6dbvarylen\f1
Indicates whether the column's data can vary in length.
.mc
.H3 "Compute Result Column Information"
.LP
These routines can be called after \f2dbsqlexec()\f1 returns
SUCCEED.
.IP \f6dbnumcompute\f1 18
Returns the number of COMPUTE clauses in the current set of results.
.IP \f6dbnumalts\f1
Returns the number of columns in a compute row.
.IP \f6dbbylist\f1
Returns the bylist for a compute row.
.IP \f6dbaltop\f1
Returns the type of aggregate operator for a compute column.
.IP \f6dbalttype\f1
Returns the datatype for a compute column.
.IP \f6dbaltlen\f1
Returns the maximum length for a compute column's data.
.IP \f6dbaltcolid\f1
Returns the column id for a compute column.
.IP \f6dbadlen\f1
Returns the actual length of a compute column's data.
This routine is often used in conjunction with \f2dbadata()\f1.
The value returned by \f2dbadlen()\f1 is different for each compute row read by
\f2dbnextrow()\f1.
.H3 "Row Buffer Information"
.LP
These macros return information that can be useful
when manipulating result rows in buffers.
.IP \f6DBFIRSTROW\f1 18
Returns the number of the first row in the buffer.
.IP \f6DBLASTROW\f1
Returns the number of the last row in the buffer.
.H3 "Command State Information"
.LP
These routines return information about the current state of the command batch.
Several of them return information about the ``current'' command\(emthat is,
the command currently being processed by \f2dbresults()\f1.
.IP \f6DBCURCMD\f1 18
Returns the number of the current command in a batch.
.IP \f6dbgetoff\f1
Checks for the existence of specified \*N constructs in the
command buffer.
This routine is used in conjunction with the DBOFFSET option.
.Ih "DBOFFSET option"
.IP \f6DBMORECMDS\f1
Indicates whether there are more commands in the batch.
.IP \f6DBCMDROW\f1
Indicates whether the current command is one that can return rows
(\f2i.e.,\f1 a SELECT or a stored procedure containing a SELECT).
.IP \f6DBROWS\f1
Indicates whether the current command actually did return rows.
.IP \f6DBCOUNT\f1
Returns the number of rows affected by a command.
.IP \f6DBNUMORDERS\f1
Returns the number of columns specified in a SELECT command's ORDER BY clause.
.IP \f6dbordercol\f1
Returns the id of a column appearing in a SELECT command's ORDER BY clause.
.H3 "Miscellaneous Information"
.LP
.IP \f6DBCURROW\f1 18
Returns the number of the row currently being read.
.IP \f6DBROWTYPE\f1
Indicates whether the current result row is a regular row or a compute row.
.IP \f6DBISAVAIL\f1
Indicates whether a DBPROCESS is available for general use.
.IP \f6dbname\f1
Returns the name of the current database.
.IP \f6dbchange\f1
Indicates whether a command batch has changed the current database.
.IP \f6dbgetmaxprocs\f1
Indicates the current maximum number of simultaneously open DBPROCESSes.
.mc |
.H2 "Browse Mode"
.Ih "browse mode routines"
.Ih "routines, browse mode"
Browse mode provides a means for browsing through database rows and updating
their values a row at a time.
From the standpoint of the program,
the process involves several steps, because
each row must be transferred from the database into program
variables before it can be browsed and updated.
.LP
Since a row being browsed is not the actual row residing in the database,
but is instead a copy residing in program variables, the program
must be able to ensure that changes to the variables' values can be reliably
used to update the original database row.
.Ih "updating the database"
.Ih "database updates"
.Ih "multi-user updates"
.Ih "updates, multi-user"
In particular, in multi-user situations, the program needs to ensure that
updates made to the database by one user do not unwittingly overwrite
updates recently made by another user.
This can be a problem because the application typically selects a number of
rows from the database at one time, but the application's users
browse and update the database one row at a time.
A \f2timestamp\f1 column in browsable database tables provides the information
necessary to regulate this type of multi-user updating.
.Ih "timestamp, browse mode"
.LP
Browse mode routines also allow an application to handle ad hoc queries.
.Ih "ad hoc queries, processing"
.Ih "queries, ad hoc"
Several of them return information that an application can use to
examine the structure of
a complicated ad hoc query in order to update the underlying database tables.
.LP
Conceptually, browse mode involves three steps:
.Ih "browse mode, steps"
.Bl 1.
Select result rows containing columns derived from one or more database tables.
.Bl 2.
Where appropriate,
change values in columns of the result rows (\f2not\f1 the actual database rows),
one row at a time.
.Bl 3.
Update the original database tables, one row at a time,
using the new values in the result rows.
.Bz
.LP
These steps are implemented in a program as follows:
.Bl 1.
Execute a SELECT command, generating result rows containing result columns.
The SELECT command must include the FOR BROWSE option.
.Bl 2.
Copy the result column values into program variables, one row at a time.
.Bl 3.
If appropriate,
change the variables' values (possibly in response to user input).
.Bl 4.
If appropriate, execute an UPDATE command that updates
the database row corresponding to the current result row.
To handle multi-user updates,
the WHERE clause of the UPDATE command must reference the timestamp column.
Such a WHERE clause can be obtained via the \f2dbqual()\f1 function.
.Ih dbqual
.Bl 5.
Repeat the second, third, and fourth steps for each result row.
.Bz
.LP
To use browse mode, the following conditions must be true:
.Bl
The SELECT command must end with the key words FOR BROWSE.
.Bl
The table(s) to be updated must be ``browsable'' (\f2i.e.,\f1 each must have
a unique index and a timestamp column).
.Ih "table, browsable"
.Ih "browsable table"
.Bl
The result columns to be used in the updates must be ``updatable''\(emthey
must be derived from browsable tables
and cannot be the result of SQL expressions, such as ``max(colname)''.
.Ih "updatable result columns"
.Ih "columns, updatable"
In other words, there must be a valid correspondence between the result column and
the database column to be updated.
.Bz
In addition, browse mode usually requires two DBPROCESSes\(emone for selecting
the data and another for performing updates based on the selected data.
.LP
For examples of browse mode programming, see the \f2\*L Reference Supplement\f1.
.LP
The following constitute the browse mode routines:
.IP \f6dbqual\f1 18
Returns a pointer to a WHERE clause suitable for use in updating the current
row in a browsable table.
.IP \f6dbfreequal\f1
Frees the memory allocated by \f2dbqual()\f1.
.IP \f6dbtsnewval\f1
Returns the new value of the timestamp column after a browse-mode update.
.IP \f6dbtsnewlen\f1
Returns the length of the new value of the timestamp column after a browse-mode update.
.IP \f6dbtsput\f1
Puts the new value of the timestamp column into the given table's current row
in the DBPROCESS.
.IP \f6dbcolbrowse\f1
Indicates whether the source of a result column is updatable via browse mode.
.IP \f6dbcolsource\f1
Returns a pointer to the name of the database column from which the specified
result column was derived.
.IP \f6dbtabbrowse\f1
Indicates whether a particular table is updatable via browse mode.
.IP \f6dbtabcount\f1
Returns the number of tables involved in the current SELECT command.
.IP \f6dbtabname\f1
Returns the name of a table based on its number.
.IP \f6dbtabsource\f1
Returns the name and number of the table from which a particular result column
was derived.
.H2 "Text and Image Handling"
.Ih "text handling routines"
.Ih "image handling routines"
.Ih "routines, text and image handling"
Since text and image values can be quite large, several routines are available to facilitate
the process of updating text and image columns in database tables:
.IP \f6dbwritetext\f1 18
Sends a text or image value to the \*S.
.IP \f6dbmoretext\f1
Sends part of a text or image value to the \*S.
.IP \f6dbtxptr\f1
Returns the text pointer for a column in the current results row.
.Ih "pointer, text"
.Ih "text pointer"
.IP \f6dbtxtimestamp\f1
.Ih "timestamp, text"
.Ih "text timestamp"
Returns the value of the text timestamp for a column in the current results row.
.IP \f6dbtxtsnewval\f1
Returns the new value of a text timestamp after a call to \f2dbwritetext()\f1.
.IP \f6dbtxtsput\f1
Puts the new value of a text timestamp into the specified column of the current
row in the DBPROCESS.
.mc
.H2 "Datatype Conversion"
.Ih "datatype conversion routines"
.Ih "conversion routines"
.Ih "routines, datatype conversion"
\*L supports conversions between most \*S datatypes with the \f2dbconvert()\f1 routine.
For information on \*S datatypes, see the \f2types\f1 manual page at the end of Section 2.
.LP
The \f2dbbind()\f1 and \f2dbaltbind()\f1 routines, which bind result columns to program
variables, can also be used to perform type conversion.
Those routines each contain a parameter that specifies the datatype of the receiving program
variable.
If the data being returned from the \*S is of a different datatype,
\*L will usually convert it automatically to the type specified by the parameter.
.IP \f6dbconvert\f1 18
.Ih dbconvert
Converts data from one \*S datatype to another.
.IP \f6dbwillconvert\f1
Indicates whether a specified datatype conversion is supported.
.H2 "Process Control Flow"
.Ih "process control flow routines"
.Ih "control flow routines"
.Ih "routines, process control flow"
These routines allow the application to schedule its actions around its interaction
with the \*S.
.IP \f6dbsetbusy\f1 18
Calls a user-supplied function when \*L is reading or waiting to read
results from the \*S.
.IP \f6dbsetidle\f1
Calls a user-supplied function when \*L is finished reading from the \*S.
.IP \f6dbsetinterrupt\f1
Calls user-supplied functions to handle interrupts while waiting on a read from the \*S.
.IP \f6DBIORDESC\f1
\f2UNIX\(rg only\f1.
Provides access to the UNIX file descriptor used to read data coming from the \*S,
allowing the application to respond to multiple input data streams.
.IP \f6DBIOWDESC\f1
\f2UNIX only\f1.
Provides access to the UNIX file descriptor used to write data to the \*S,
allowing the application to effectively utilize multiple input
and output data streams.
.IP \f6DBRBUF\f1
\f2UNIX only\f1.
Determines whether the \*L network buffer contains any unread bytes.
.mc |
.IP \f6dbcancel_a\f1
.Ss \f2VMS\fP TM
\f2only\f1.
The asynchronous version of \f2dbcancel()\f1.
.Ih "asynchronous routines (VMS)"
.IP \f6dbnextrow_a\f1
\f2VMS only\f1.
The asynchronous version of \f2dbnextrow()\f1.
.IP \f6dbopen_a\f1
\f2VMS only\f1.
The asynchronous version of \f2dbopen()\f1.
.IP \f6dbresults_a\f1
\f2VMS only\f1.
The asynchronous version of \f2dbresults()\f1.
.IP \f6dbsqlexec_a\f1
\f2VMS only\f1.
The asynchronous version of \f2dbsqlexec()\f1.
.mc
.mc |
.H2 "Remote Procedure Call Processing"
.Ih "remote procedure calls, processing"
.Ih "stored procedures, calling remotely"
.Ih "calls, remote procedure"
A remote procedure call is simply a call to a stored
procedure residing on a remote server.
Either an application or another server makes the call.
A remote procedure call made by an application has
the same effect as an EXECUTE command\(emit executes the stored procedure,
generating results accessible through \f2dbresults()\f1.
However, a remote procedure call is often more efficient than an EXECUTE command.
.LP
A server can make a remote procedure call to another server.
This occurs when a stored procedure being executed on one server
contains an EXECUTE command for a stored procedure on another server.
The EXECUTE command causes the first server to log into the second
server and perform a remote procedure call on the procedure.
This happens without any intervention from the application,
although the application can specify the remote password which the
first server uses to log in.
.IP \f6dbrpcinit\f1 18
Initializes a remote procedure call to a stored procedure.
.IP \f6dbrpcparam\f1
Adds a parameter to a remote procedure call.
.IP \f6dbrpcsend\f1
Signals the end of a remote procedure call, causing the server
to begin executing the specified procedure.
.IP \f6dbrpwset\f1
Adds a remote password to a LOGINREC structure.
The server will use this password when it
performs a remote procedure call on another server.
.IP \f6dbrpwclr\f1
Clears all remote passwords from a LOGINREC structure.
.mc
.H2 "Cleanup"
.Ih "cleanup routines"
.Ih "routines, cleanup"
These routines sever the connection between the application and the \*S.
.IP \f6dbexit\f1 18
.Ih dbexit
Closes and de-allocates all DBPROCESS structures.
.mc |
This routine also cleans up any structures initialized by \f2dbinit()\f1.
.mc
.IP \f6dbclose\f1
.Ih dbclose
Closes and de-allocates a single DBPROCESS structure.
.H2 "Miscellaneous Routines"
.Ih "miscellaneous routines"
.Ih "routines, miscellaneous"
.IP \f6dbsetavail\f1 18
Marks a DBPROCESS as being available for general use.
.IP \f6dbsetmaxprocs\f1
Sets the maximum number of simultaneously open DBPROCESSes.
.mc |
.IP \f6dbsetuserdata\f1
Uses a DBPROCESS structure to save a pointer to user-allocated
data.
This routine, along with \f2dbgetuserdata()\f1, allows the application
to associate user data with a particular DBPROCESS.
One important use for these routines is to transfer information
between a \*S message handler and the program code that triggered it.
.IP \f6dbgetuserdata\f1
Returns a pointer to user-allocated data from a DBPROCESS structure.
.mc
.IP \f6dbsetnull\f1
Defines substitution values to be used when binding null values.
.IP \f6dbprtype\f1
Converts a \*S type token into a readable string.
Tokens are returned by various routines such as \f2dbcoltype()\f1 and \f2dbaltop()\f1.
.IP \f6dbreadpage\f1
Reads in a page of binary data from the \*S.
.IP \f6dbwritepage\f1
Writes a page of binary data to the \*S.
.H2 "Bulk Copy Special Library"
.Ih "bulk copy special library"
.Ih "bcp routines"
.Ih "library, bulk copy"
The routines in this library allow an application to bulk
copy data in and out of the \*S.
They provide a facility for high-speed loading of data
into the \*S from either files or program variables.
.Ih "data, high-speed loading of"
They also allow you to copy data out
of the \*S into files, using a pre-defined format.
The bulk copy routines are similar in function
to the \f2bcp\f1 utility
program, described in the \f2Commands Reference\f1.
.Ih "bcp utility"
.mc |
.IP \f6BCP_SETL\f1 18
Sets the LOGINREC for bulk copy operations.
.IP \f6bcp_init\f1
Initializes bulk copy.
.IP \f6bcp_bind\f1
Binds data from a program variable to a \*S table.
.IP \f6bcp_sendrow\f1
Sends a row of data from program variables to the \*S.
.IP \f6bcp_moretext\f1
Sends part of a text or image value to the \*S.
.IP \f6bcp_collen\f1
Sets the program variable data length for the current copy IN.
.IP \f6bcp_colptr\f1
Sets the program variable data address for the current copy IN.
.IP \f6bcp_batch\f1
Saves any preceding rows in the \*S.
.IP \f6bcp_done\f1
Ends a bulk copy from program variables into the \*S.
.IP \f6bcp_control\f1
Changes various control parameter default settings.
.IP \f6bcp_columns\f1
Sets the total number of columns found in the host file.
.IP \f6bcp_colfmt\f1
Specifies the format of a host file for bulk copy purposes.
.IP \f6bcp_exec\f1
Executes a bulk copy of data between a database table and a host file.
.mc
.H2 "Two-Phase Commit Service Special Library"
.Ih "two-phase commit service special library"
.Ih "library, two-phase commit service"
The routines in this library allow an application to
coordinate updates among two or more SQL Servers.
See the introduction to this library in Section 3 for detailed information
on the two-phase commit service.
.IP \f6open_commit\f1 18
Establishes a connection with the commit service.
.IP \f6start_xact\f1
Starts a distributed transaction using the commit service.
.IP \f6build_xact_string\f1
Builds a name for a distributed transaction.
.IP \f6commit_xact\f1
Marks a distributed transaction as being committed.
.IP \f6abort_xact\f1
Marks a distributed transaction as being aborted.
.IP \f6stat_xact\f1
Returns the current status of a distributed transaction.
.IP \f6remove_xact\f1
Decrements the count of sites still active in the distributed transaction.
.IP \f6scan_xact\f1
Prints commit service record for distributed transactions.
.IP \f6close_commit\f1
Ends a connection with the commit service.
.H1 "What's in this Book"
.Ih "\*L Reference Manual, contents of"
Section 2 contains separate manual pages for each of the \*L routines.
Each manual page includes:
.Bl
A summary of the routine's function.
.Bl
The syntax of the routine's calling interface.
.Bl
A thorough description of the routine, including issues of syntax, usage, and
run-time behavior.
.Bl
Descriptions of each of the routine's parameters.
.Bl
Descriptions of the routine's return values, if any.
.Bl
A list of related routines.
.Bz
.LP
Section 3 contains manual pages for the special library routines.
The Bulk Copy library is presented first, followed by the Two-Phase Commit Service library.
Section 3 also provides an introduction to
the two-phase commit service.
.LP
In the back of the book you'll find
Appendix A, an alphabetical listing of all \*L routines.
.LP
.mc |
A companion document,
the \f2\*L Reference Supplement\f1, provides
system-specific material on \*L.
Separate versions of the \f2Supplement\f1 exist
for each operating system that \*L runs on.
The \f2\*L Reference Supplement\f1 begins with a section that describes
how to compile and link \*L code.
A number of short example programs, which illustrate
various \*L routines, follow.
The source code for the examples is supplied with your installation
and may be compiled and run.
.mc
.H1 "Related Documents"
.Ih "documents, related"
The SYBASE document set includes a wide range of user guides and reference manuals,
which describe all aspects of the SYBASE relational database management system.
Because application development can draw on a number of different parts of the SYBASE system,
you may encounter most of the SYBASE document set at some time or another.
A few manuals, however, will prove to be particularly useful:
.Bl
\f2Commands Reference\f1 and \f2\*N User's Guide\f1 document the \*N
database language.
.Ih "Commands Reference"
.Ih "\*N User's Guide"
.Bl
\f2\*A User's Guide\f1 documents \*A, the editor used to create forms and
specify their processing.
.Ih "\*A User's Guide"
.Bl
\f2\*F Reference Manual\f1 describes the library of C functions that give an
application access to forms and their objects.
.Ih "\*F Reference Manual"
.Bz
.LP
In addition, versions of \*L and \*F are available for a number of other
languages, including COBOL, FORTRAN, Ada, and Pascal.  If you are interested in obtaining \*L
and \*F manuals for those languages, contact your SYBASE sales representative.
.Ih "COBOL/\*L"
.Ih "FORTRAN/\*L"
.Ih "Ada/\*L"
.Ih "Pascal/\*L"